#region Header

// MS codename Velocity Distributed Cache Extensions.
// (c) 2009

#endregion


#region Usings

using System;

#endregion


namespace Caching.Extensions.Core
{
    /// <summary>
    /// Smart Cache interface
    /// </summary>
    public interface ISmartCache
    {
        #region Get operations 

        /// <summary>
        /// Get item from cache
        /// </summary>
        /// <param name="key">Item key</param>
        /// <returns>Item or null, if item expired</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords")]
        object Get(string key);


        /// <summary>
        /// Get item from cache region
        /// </summary>
        /// <param name="region">Region name</param>
        /// <param name="key">Item key</param>
        /// <returns>item or null if item expired</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords")]
        object Get(string key, string region);

        #endregion Get operations


        #region Put operations 

        /// <summary>
        /// Put item to cache with default expiration
        /// </summary>
        /// <param name="key">item key</param>
        /// <param name="value">value</param>
        void Put(string key, object value);


        /// <summary>
        /// Put item to cache
        /// </summary>
        /// <param name="key">Item key</param>
        /// <param name="value">value</param>
        /// <param name="timeout">expiration timeout</param>
        void Put(string key, object value, TimeSpan timeout);


        /// <summary>
        /// Put item into particular region
        /// </summary>
        /// <param name="key">item key</param>
        /// <param name="value">value</param>
        /// <param name="region">region name</param>
        void Put(string key, object value, string region);


        /// <summary>
        /// Put item into particular region with expiration 
        /// </summary>
        /// <param name="key">item key</param>
        /// <param name="value">value</param>
        /// <param name="timeout">expiration timeout</param>
        /// <param name="region">region</param>
        void Put(string key, object value, TimeSpan timeout, string region);

        #endregion Put operations


        /// <summary>
        /// OnRemove item from cache
        /// </summary>
        /// <param name="key">Itm key</param>
        /// <returns>True if removed sucessfully, false if no such item in cache</returns>
        bool Remove(string key);


        /// <summary>
        /// OnRemove item from cache region
        /// </summary>
        /// <param name="key">item key</param>
        /// <param name="region">Region name</param>
        /// <returns>True if removed sucessfully, false if no such item in cache region</returns>
        bool Remove(string key, string region);


        #region Region support 

        /// <summary>
        /// Create cache region
        /// </summary>
        /// <param name="region">name of region to create</param>
        /// <param name="evictionOn">true if items can be evicted</param>
        /// <returns>True, if region was created. False if region already exists.</returns>
        bool CreateRegion(string region, bool evictionOn);


        /// <summary>
        /// OnRemove cache region
        /// </summary>
        /// <param name="region">name of region to remove</param>
        /// <returns>True, if region was removed. False if region does not exists.</returns>
        bool RemoveRegion(string region);

        #endregion Region support


        SmartCacheEventPublisher NotificationEvents { get; }
    }
}